Justification

Added a React demo web application using Vite to demonstrate how a customer might create a webApp and deploy it to SystemLink. The webApp demos how to call SystemLink APIs both in development (locally) and in production (within a SystemLink website).

The github actions webApp workflow automates building, linting, and deployment to the SystemLink website. The workflow also outputs a .nipkg artifact of the webApp to github. See /.github/workflows/webapp_deploy.yml

Implementation

• Webapp Design

  • The web app was created in TypeScript/React with nimble design components
  • see examples/web_apps/Framework_Examples/React/ApiKeyAuthApp

• Running in Development (locally) vs Production (hosted in SystemLink website)

  • Environment (.env.development and .env.production) files allow variable domain for fetches (dev will fetch from the local proxy server, prod will fetch from the hosting website)

• ApiServiceProxy -- Required to run web app locally

  • To run in development, developers must call a SystemLink API URL with an API key
  • A proxy is required in order to circumvent browser CORS issues
  • The proxy also allows for API authentication in development and session
    token authentication when the web app is hosted in the SystemLink website
  • Setup instructions for the proxy are included in ApiServiceProxy/README.md

• Production -- Running inside SystemLink Website

  • In production, the webApp will call the same APIs but from the hosting SystemLink website domain (instead of an API URL)
  • Instructions for deploying the webApp to production are included in the ApiKeyAuthApp/README.md
  • For developers, the deployment steps are also automated in ./deployDev.sh

• Workflow -- Building, Linting, Deployment to SystemLink website

  • Most of the workflow relies on npm scripts defined in a webApp's package.json (npm ci, npm lint, npm build).
    • This will work for any node.js project, but will need to change for future wasm apps such as blazor
      • Change will likely be using shell scripts instead of package manager scripts
  • Each webApp folder must be added to the job matrix to be included in the script

• SystemLink CLI (SL CLI) integration in Workflow

  • The SL CLI was installed into the workflow by using brew (brew was provided on the github-runner, but needed to be added to the env path)
  • The SL CLI allows for:
    • Packaging a webApp into an .nipkg file
    • Deploying to a user's workspace
  • Github Secrets
    • The workflow includes secrets which will allow any developer to copy the workflow and use it for CI/CD
    • Required secrets for the workflow:
      • SL_API_URL
      • SL_API_KEY
      • SL_WEBSITE_URL
      • SL_WORKSPACE

Testing

• Local env

  • The webApp was run locally on a few devices using the proxy server and successfully called the API.

• Within SystemLink website

  • The webApp was also successfully deployed to SystemLink website, where it was able to call the API for the logged in user.

• Workflow

  • The workflow was tested a couple of times on pushes to our fork's devOps branch. The workflow successfully built, packaged, and deployed the web application!

Checklist

• I have read and followed the Contributing Guidelines